/*
 * Created on 2005-10-9
 *
 */
package com.hd123.rumba.user;

import java.util.List;

import net.sf.hibernate.HibernateException;

import com.hd123.rumba.domain.IDomain;
import com.hd123.rumba.exception.BusinessException;
import com.hd123.rumba.runtime.IManager;
import com.hd123.rumba.runtime.OperateContext;

/**
 * @author caili
 */
public interface IRoleMgr extends IManager {

  public IRole createRole(IDomain domain, String code, String name) throws HibernateException,
      BusinessException;

  /**
   * 创建一个新的角色。
   * 
   * @param domain
   *          被创建角色所属域。
   * @return 被创建的角色。
   * @throws HibernateException
   * @throws BusinessException
   */
  public IRole createRole(IDomain domain) throws HibernateException, BusinessException;

  /** @deprecated */
  public void saveRole(IRole role) throws HibernateException, BusinessException;

  /**
   * 保存角色
   * 
   * @param role
   *          被保存的角色
   * @param operator
   * @param oca
   * @throws HibernateException
   * @throws BusinessException
   * @deprecated
   */
  public void saveRole(IRole role, IUser operator, long oca) throws HibernateException,
      BusinessException;

  /**
   * 保存角色
   * 
   * @param role
   *          被保存的角色
   * @param operate
   * @throws HibernateException
   * @throws BusinessException
   */
  public void saveRole(IRole role, OperateContext operate) throws HibernateException,
      BusinessException;

  public void removeRole(IRole role, OperateContext operate) throws HibernateException,
      BusinessException;

  /**
   * （标记）删除指定的角色。
   * 
   * @param role
   *          被标记删除的角色。
   * @param operate
   * @throws HibernateException
   * @throws BusinessException
   */
  public void deleteRole(IRole role, OperateContext operate) throws HibernateException,
      BusinessException;

  /**
   * 恢复删除指定的角色。
   * 
   * @param role
   *          被恢复删除的角色。
   * @param operate
   * @throws HibernateException
   * @throws BusinessException
   */
  public void undeleteRole(IRole role, OperateContext operate) throws HibernateException,
      BusinessException;

  /**
   * 根据uuid取得角色。
   * 
   * @param uuid
   *          角色的uuid。
   * @return 返回符合条件的角色，若未找到则返回null。
   * @throws HibernateException
   * @throws BusinessException
   */
  public IRole getRole(String uuid) throws HibernateException, BusinessException;

  /**
   * 根据uuid取得角色。
   * 
   * @param uuid
   *          角色的uuid。
   * @param states
   *          符合条件的角色状态取值列表，只有当角色的状态属于该集合时才会被返回。传入null，表示不约束状态条件。
   * @return 返回符合条件的角色，若未找到则返回null。
   * @throws BusinessException
   * @throws HibernateException
   */
  public IRole getRole(String uuid, Integer[] states) throws BusinessException, HibernateException;

  /**
   * 根据uuid取得可用的角色。即状态不等于“已删除”的角色。
   * 
   * @param uuid
   *          角色的uuid。
   * @return 返回符合条件的角色，若未找到则返回null。
   * @throws BusinessException
   * @throws HibernateException
   */
  public IRole getValidRole(String uuid) throws BusinessException, HibernateException;

  /**
   * 根据代码取得角色。
   * <p>
   * 仅搜索可用的角色，即不包括状态为已删除的角色。
   * 
   * @param domain
   *          角色所属域。
   * @param code
   *          角色的代码。
   * @return 返回符合条件的角色，若未找到则返回null。
   * @throws HibernateException
   * @throws BusinessException
   */
  public IRole getRoleByCode(IDomain domain, String code) throws HibernateException,
      BusinessException;

  /** @deprecated */
  public void assignPermissionToRole(IPermission perm, IRole role) throws HibernateException,
      BusinessException;

  /**
   * 向角色添加权限
   * 
   * @param perm
   *          被添加的权限
   * @param role
   *          指定的角色
   * @param operate
   * @throws HibernateException
   * @throws BusinessException
   */
  public void assignPermissionToRole(IPermission perm, IRole role, OperateContext operate)
      throws HibernateException, BusinessException;

  /** @deprecated */
  public void removePermissionFromRole(IPermission perm, IRole role) throws HibernateException,
      BusinessException;

  /**
   * 从角色中删除权限
   * 
   * @param perm
   *          被删除的权限
   * @param role
   *          指定的角色
   * @param operate
   * @throws HibernateException
   * @throws BusinessException
   */
  public void removePermissionFromRole(IPermission perm, IRole role, OperateContext operate)
      throws HibernateException, BusinessException;

  public boolean hasPermission(IRole role, IPermission perm) throws HibernateException,
      BusinessException;

  /**
   * @param role
   * @return List of IPermission
   * @throws HibernateException
   */
  public List createPermissionsList(IRole role) throws HibernateException, BusinessException;

  /**
   * 取得指定拥有指定角色的用户。<br>
   * 仅包括所有可用的用户。
   * 
   * @param role
   *          指定的角色。
   * @return List of IUser 返回用户列表。
   * @throws HibernateException
   */
  public List createUsersList(IRole role) throws HibernateException, BusinessException;

  /**
   * @param domain
   * @return List of IRole
   * @throws HibernateException
   */
  public List createAllRolesList(IDomain domain) throws HibernateException, BusinessException;

  public List createUsersListByRoleAndDomain(IRole role, IDomain domain) throws HibernateException,
      BusinessException;

  /**
   * 将公共角色共享给指定的域。
   * 
   * @param role
   *          指定的公共角色
   * @param domain
   *          目标域
   * @param operate
   *          操作上下文
   * @throws HibernateException
   * @throws BusinessException
   */
  public void shareRoleToDomain(IRole role, IDomain domain, OperateContext operate)
      throws HibernateException, BusinessException;

  /**
   * 取消公共角色对指定的域的共享。
   * 
   * @param role
   *          指定的公共角色
   * @param domain
   *          目标域
   * @param operate
   *          操作上下文
   * @throws HibernateException
   * @throws BusinessException
   */
  public void unshareRoleFromDomain(IRole role, IDomain domain, OperateContext operate)
      throws HibernateException, BusinessException;

  /**
   * 取得角色共享给的域的列表。
   * 
   * @param role
   *          指定的公共角色
   * @return 角色列表
   * @throws BusinessException
   * @throws HibernateException
   */
  public List<IDomain> createRoleShareDomains(IRole role) throws BusinessException,
      HibernateException;
}
